# Creating a new Custom Field

This endpoint returns structured Custom Field objects.
As with all Kantata OX API endpoints, the returned data will be referenced in sorted order in the `results` array
and will be indexed by ID in the `custom_fields` top-level JSON key.
Please see our [Response Format](#section/Response-Format) section for more information.

Endpoint: POST /custom_fields
Version: 1.0.0

## Query parameters:

  - `include` (string)
    Any of the below associations can be included in your request by providing the `include` param, e.g. `include=association1,association2`.
- `choices`
 (CustomFieldChoice) - Includes the ID of a Custom Field's choices.
- `creator`
 (User) - Includes the ID of a Custom Field's creator.
- `custom_field_set`
 (CustomFieldSet) - Includes the ID of the Custom Field Set that a field belongs to.
- `external_references`
 (ExternalReference) - Includes references to external integrations for this object.

## Request fields (application/json):

  - `custom_field` (object)

  - `custom_field.name` (string, required)
    The name of the new field.

  - `custom_field.value_type` (string)
    The format of the [custom field's value](/tag/Custom-Field-Values):
| Value Type | Format | Sample |
|  --- | --- | --- |
| `string` | `<text_string>` | `"foo"` |
| `date` | `<ISO_8601 Date Format>` | `"2014-02-25"` |
| `number` | `<integer_value>` | `13` |
| `currency` | `[<int_value_in_cents>, <currency_code>]` | `[998, "USD"]` |
| `single` and `multi` | `[<choice_ids>]` | `[1, 2, 4]` |

This is set to `string` by default.

  - `custom_field.default_text` (string)
    The message in an empty custom field, before a `string`, `date`, `number`, or `currency`  value is entered in.
This only appears in the UI.

  - `custom_field.unique_constraint` (boolean)
    A boolean setting that requires a custom field value to be unique across Estimates, Projects, Groups,
Resources, Tasks, or Users.
This is set to `false` by default.

  - `custom_field.choices` (array)
    The list of [choices](/tag/Custom-Field-Choices) a user can select from
for a custom field's value(s). A choice has two attributes, a `label` and an `ID`. Different choices can have the
same `label`, but every choice will have a unique `ID`.
For example, a request:

```
custom_field_choices: {
  ....
  choices: [
    { "label": "Choice A" },
    { "label": "Choice B" },
    { "label": "Choice B" },
    { "label": "Choice B" }
  ]
  ....
}

Will have a response like:
```
custom_field_choices: {
....
choices: [
{ "label": "Choice A", "id": "180291" },
{ "label": "Choice B", "id": "180301" },
{ "label": "Choice B", "id": "180311" },
{ "label": "Choice B", "id": "180321" }
]
....
}

```

Choices in the UI appear in the same order as listed in the array.

Note that the 2nd, 3rd, and 4th choices all have the same label, but different IDs.
```

  - `custom_field.choices.label` (string)
    You can think of a label as the actual value a user can select for the custom field.
*Note:* Different choices can have the same `label`.

  - `custom_field.custom_field_set_id` (integer)
    The ID of the [Custom Field Set](/tag/Custom-Field-Sets) that the field belongs to.
When a set ID is not specified, the field is added to a Project set titled 'Default Project Set'.
This means it becomes a Project field.

  - `custom_field.write_access` (string)
    The permission level required for a user to create, update, or delete a custom field's value.

  - `custom_field.read_access` (string)
    The `read_access` [permission setting on each custom field](https://knowledge.kantata.com/hc/en-us/articles/202924760#see)
determines the minimum permission needed to view a custom field and its value.
* `Workspace`
 (Project),
`Resource`
, and
`Story`
 (Task) custom fields are project-specific objects,

so their minimum permissions are set at the
[project level](https://knowledge.kantata.com/hc/en-us/articles/115002779293-Project-Permissions)
:
  - `project_collaboration`
 (default)
  - `time_logging`
  - `financial`
  - `project_admin`

Most account-level permissions supercede project-level permissions. Therefore, Account Administrators are able to view
all Project, Resource, and Task custom fields and values across the account, regardless of project participation or
`read_access` settings.
* `Estimate`
,
`WorkspaceGroup`
 (Group), and
`User`
 custom fields are account-wide objects, so their minimum permissions

are set at the
[account level](https://knowledge.kantata.com/hc/en-us/articles/203041364)
:
  - `account_collaboration`
  - `project_creator`
  - `project_lead`
  - `reports_viewer`
  - `reports_viewer_with_cost`
  - `account_admin`
 (default).

## Response 200:

  - `200` (unknown)
    Custom Field has been created.

## Response 200 fields (application/json):

  - `count` (integer)

  - `meta` (object)

  - `meta.count` (integer)

  - `meta.page_count` (integer)

  - `meta.page_number` (integer)

  - `meta.page_size` (integer)

  - `results` (array)

  - `results.key` (string)

  - `results.id` (string)

  - `custom_fields` (object)

  - `external_references` (object)

  - `users` (object)

  - `custom_field_choices` (object)

  - `custom_field_sets` (object)

## Response 400:

  - `400` (unknown)
    Bad Request

## Response 400 fields (application/json):

  - `errors` (array)

  - `errors.type` (string)

  - `errors.message` (string)

## Response 401:

  - `401` (unknown)
    Unauthorized request

## Response 401 fields (application/json):

  - `errors` (array)

  - `errors.type` (string)

  - `errors.message` (string)

## Response 403:

  - `403` (unknown)
    Forbidden request

## Response 403 fields (application/json):

  - `errors` (array)

  - `errors.type` (string)

  - `errors.message` (string)

## Response 404:

  - `404` (unknown)
    Page Not Found

## Response 404 fields (application/json):

  - `errors` (array)

  - `errors.type` (string)

  - `errors.message` (string)

## Response 422:

  - `422` (unknown)
    Unprocessable Entity

## Response 422 fields (application/json):

  - `errors` (array)

  - `errors.type` (string)

  - `errors.message` (string)

## Response 503:

  - `503` (unknown)
    Service is unavailable

## Response 503 fields (application/json):

  - `errors` (array)

  - `errors.type` (string)

  - `errors.message` (string)